Bug: this clears the entire application cache, not just PPR entries.

Rails.cache.clear evicts session data, fragment caches, and any other cached content sharing the same store. In a shared development environment (or if this route is ever reachable in staging) it becomes a silent DoS against every other cache consumer.

Scope the invalidation to PPR keys instead:

Alternatively, store PPR keys in a dedicated cache store (e.g. :ppr_store) and call .clear on that.

Fragile AbortError detection: silently swallows any error whose message contains "aborted".

A legitimate component error like new Error("request aborted by user") or new Error("AbortError: network timeout") will be suppressed here, hiding real bugs during prerender.

Prefer checking the abort signal's state first (it's already in scope), then fall back to the standard DOMException name:

Potential double error emission when throwJsErrors is true.

runResume's own catch block calls emitError(error) when throwJsErrors is true (line 361), which consumes the error. But if emitError itself throws (or if another uncaught exception escapes the try block that the inner catch misses), the outer .catch at line 370 fires and calls emitError a second time on the already-closed/errored stream, which can cause write after end or similar stream errors.

runResume exhaustively handles its own errors, so the outer .catch should only exist as a last-resort safety net—it should not re-emitError unconditionally. Consider:

Fragile stub-timer detection: the undefined return value is an undocumented implementation detail.

This check assumes the Pro node renderer's stubbed setTimeout returns undefined. If the stub is ever changed to return 0 or null (both falsy but not undefined/null), real timers would be incorrectly flagged as stubbed. Similarly, a real Node.js Timeout object with a zero timeout fires almost immediately, so the timer scheduled here actually runs — leaking a no-op tick into the event loop.

A more robust approach is to explicitly check for the known RENDERER_STUB_TIMERS environment variable that already guards this behavior, or to treat the check as informational (a warning rather than a hard throw) since the actual failure mode (timer never fires) will be caught by the outer prerender timeout anyway:

shellHtml is serialized twice in the prerender response.

Both html and pprShellHtml carry the same string. For large pages (marketing pages with thousands of nodes are common PPR candidates) this doubles the JSON payload sent from the node renderer back to Ruby. The node renderer already JSON-stringifies the whole result object, so the duplication isn't free.

internal_ppr_prerender on the Ruby side reads result["pprShellHtml"] explicitly. If you drop html from the prerender return value, the Pro Ruby helper needs a small update—but that's better than sending every shell twice forever.

At a minimum, omit html from the prerender response type and remove the field here:

Update PPRPrerenderResult accordingly and confirm that no other consumer reads .html on the prerender result.

Permanent failure on transient errors: once cachedAPIError is set, every future PPR call fails without retry.

The intent is good (avoid re-resolving dynamic imports repeatedly), but if the first PPR call happens before React 19.2 is fully available (e.g., during a hot-module-replacement cycle in development, or a race at worker startup), the error is cached permanently and the worker must be restarted to recover.

For the success path, the singleton is correct. For failures, consider only caching hard version errors (React too old) while letting transient module-resolution errors retry:

Then in the catch:

} catch (e) {
  const err = convertToError(e);
  // Permanently cache only version errors; other errors (transient HMR races, etc.) can retry.
  if (err.message.includes('React on Rails Pro PPR requires React')) {
    cachedVersionError = err;
  }
  throw err;
}

Use the node: prefix for built-in module imports.

async_hooks (without prefix) is the legacy form. The canonical modern form is node:async_hooks. The prefixed form is unambiguous (can't be shadowed by a userland package named async_hooks) and is required by some linting rules and bundler configurations.

PPR render-function dispatch is duplicated verbatim in js_code_builder.rb.

JsCodeBuilder#resolve_render_function_js_expr (lines 116-126 of js_code_builder.rb) contains identical ppr_prerender?/ppr_resume? branches. When a third PPR function is ever added, a developer must update two files. One of these should delegate to the other:

# server_rendering_js_code.rb — delegate to JsCodeBuilder
render_function_name = JsCodeBuilder.new(render_options).resolve_render_function_js_expr(render_options)

Or extract a small shared module. The duplication is currently invisible because both files produce the same string, but it will silently diverge on future changes.

Demo anti-pattern: request-varying values are passed as top-level props.

currentTime and cartItemCount are evaluated on every Rails request and sent as props to both the prerender phase and the resume phase. In the prerender, the components that read these values call usePostpone(), so the values are correctly ignored during shell construction. But:

1. These values are transmitted to the node renderer on every prerender call—even on cache hits, because ppr_react_component re-invokes internal_ppr_resume (which injects them into railsContext) on every request. That's fine by design, but the demo makes it look like passing dynamic props to ppr_react_component is the right pattern, when in fact the shell's cache key ("ppr-demo-v1") is fixed and doesn't change with these values.

2. rand(0..9) in particular is a trap: if a future developer adds a static boundary that reads cartItemCount, they'll get a silently wrong (cached) value.

Consider clarifying the demo comment to make the design contract explicit:

<%# Props here are forwarded to the RESUME phase only. The static shell is cached
    independently of these values. Dynamic components must call usePostpone() to
    ensure they are excluded from the cached shell. %>
<%= ppr_react_component(
      "PPRComprehensiveDemo",
      cache_key: ["ppr-demo-v1", request.host],
      props: {
        currentTime: Time.current.iso8601(3),
        userName: cookies[:demo_user_name].presence || "Guest",
        cartItemCount: rand(0..9),
      },

pprShellHtml is injected via railsContext even during the prerender phase, where it is unused.

The ppr? guard is true for both :ppr_prerender and :ppr_resume. During prerender, pprShellHtml and pprPostponedState are always nil/null, so they serialize to null and waste bandwidth. More importantly, for the resume phase, the shell HTML (which can be hundreds of KB for complex pages) is serialized into the JS code string that is sent as the HTTP request body to the node renderer—effectively transmitting the cached shell back to the renderer that generated it in the first place.

Consider splitting this block and only injecting pprShellHtml/pprPostponedState on resume: